Skip to main content

SystemController

The SystemController provides system-wide SWMM simulation data and summary information for the entire model.

Overview​

This controller handles system-level operations including retrieving system summaries, precipitation data, runoff information, and system-wide time series data. It provides aggregated information across all model components.

Data Sources​

  • Azure Blob Storage:
    • swmm-output container for simulation results
  • Azure Table Storage:
    • SystemOutput table for system time series data
    • Runs table for run metadata
  • Configuration: appsettings.json for connection string

Endpoints​

GET /api/system/summary​

Retrieves system summary information including precipitation, dry weather inflow, and runoff.

Query Parameters:

  • step (string): Simulation timestep
  • runDateTime (string): Simulation run datetime

Response:

  • 200 OK: Returns SwmmResult object with system summary
  • 404 Not Found: Results not found
  • 500 Internal Server Error: Processing error

Data Flow:

System Summary Structure:

{
  "precipitation": 25.5,
  "runoff": 15.2,
  "dryWeatherInflow": 2.1,
  "flooding": 0.8,
  "nodes": null,
  "links": null,
  "subcatchments": null
}

GET /api/system/attributes​

Retrieves system attribute time series data with Unix timestamps.

Query Parameters:

  • systemAttribute (string): System attribute to retrieve
  • runDateTime (string): Simulation run datetime
  • scenario (string): Scenario name

Response:

  • 200 OK: Returns list of TimeSeriesPoint objects
  • 404 Not Found: Data not found
  • 500 Internal Server Error: Processing error

Data Flow:

Time Series Point Structure:

[
  {
    "simUnixTime": 1700000000000,
    "value": 25.5
  },
  {
    "simUnixTime": 1700000015000,
    "value": 26.1
  }
]

Azure Storage Details​

Blob Storage Schema​

swmm-output Container:

{partitionKey}_{scenario}_{datetime}/
├── {step}
└── ...

Blob Content: JSON format containing complete SwmmResult object

Table Storage Schema​

SystemOutput Table:

  • PartitionKey: {scenario}_{runDateTime}
  • RowKey: {systemAttribute}
  • Properties:
    • CSVSeries: JSON array of time series values
    • Timestamp: Entity timestamp
    • ETag: Entity tag for concurrency

Runs Table:

  • PartitionKey: {scenario}
  • RowKey: {runDateTime}
  • Properties: StartTime, EndTime, ReportingTimeStep, Status

Data Models​

TimeSeriesPoint​

public class TimeSeriesPoint
{
    public long simUnixTime { get; set; }  // Unix milliseconds
    public double value { get; set; }
}

SwmmResult (System Summary)​

public class SwmmResult
{
    public double Precipitation { get; set; }
    public double Runoff { get; set; }
    public double DryWeatherInflow { get; set; }
    public double Flooding { get; set; }
    public List<SwmmNodeResult> Nodes { get; set; }
    public List<SwmmLinkResult> Links { get; set; }
    public List<SwmmSubcatchmentResult> Subcatchments { get; set; }
}

SystemOutput Entity​

public class SystemOutputEntity : ITableEntity
{
    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public string CSVSeries { get; set; }
    public DateTimeOffset Timestamp { get; set; }
    public ETag ETag { get; set; }
}

Configuration​

Required Settings:

{
  "Values": {
    "CloudStorageConnectionString": "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net"
  }
}

Error Handling​

  • Storage Errors: Logged to Azure Table Storage
  • Missing Data: Returns null or empty lists
  • Invalid Parameters: Graceful parameter validation
  • Time Processing: Handles timezone and format issues
  • Data Parsing: Handles malformed JSON/CSV data

Performance Considerations​

  • Memory Management: Uses memory streams for blob operations
  • Data Parsing: Efficient JSON and CSV parsing
  • Time Calculations: Optimized Unix timestamp calculations
  • Caching: No built-in caching (consider for frequently accessed data)
  • Error Recovery: Graceful handling of missing data

Dependencies​

  • Azure.Storage.Blobs
  • Azure.Data.Tables
  • GqcStorage1 (Storage utilities)
  • SwmmModels (Data models)
  • System.Text.Json

Common System Attributes​

SystemResult Enum​

  • PRECIPITATION (0): Total precipitation
  • RUN_OFF (1): Total runoff
  • DW_INFLOW (2): Dry weather inflow
  • FLOODING (3): Total flooding

Time Series Processing​

  • Unix Timestamps: Converts to milliseconds since epoch
  • Time Steps: Uses reporting time step from run configuration
  • Time Alignment: Ensures proper time step alignment
  • Data Validation: Handles null/missing values

Usage Examples​

Get System Summary:

GET /api/system/summary?step=15&runDateTime=2023-11-16T00:00:00-05:00

Get System Time Series:

GET /api/system/attributes?systemAttribute=0&runDateTime=2023-11-16T00:00:00-05:00&scenario=scenario0

Response Examples​

System Summary Response:

{
  "precipitation": 25.5,
  "runoff": 15.2,
  "dryWeatherInflow": 2.1,
  "flooding": 0.8,
  "nodes": null,
  "links": null,
  "subcatchments": null
}

Time Series Response:

[
  {
    "simUnixTime": 1700000000000,
    "value": 25.5
  },
  {
    "simUnixTime": 1700000015000,
    "value": 26.1
  },
  {
    "simUnixTime": 1700000030000,
    "value": 24.8
  }
]

System-Wide Calculations​

Precipitation​

  • Total precipitation across all subcatchments
  • Aggregated by timestep
  • Units: depth (mm or inches)

Runoff​

  • Total surface runoff from all subcatchments
  • Aggregated by timestep
  • Units: volume (m³ or ft³)

Dry Weather Inflow​

  • Total dry weather inflow to all nodes
  • Aggregated by timestep
  • Units: flow rate (m³/s or ft³/s)

Flooding​

  • Total flooding from all nodes
  • Aggregated by timestep
  • Units: volume (m³ or ft³)

Data Quality Considerations​

  • Aggregation Accuracy: Ensures proper summation across components
  • Time Alignment: Maintains consistent timestep alignment
  • Unit Consistency: Maintains proper units throughout
  • Data Validation: Validates system data consistency
  • Error Recovery: Graceful handling of data corruption

Monitoring and Analysis​

System Performance Metrics​

  • Total Volume: Aggregated volumes across all components
  • Peak Values: Maximum values during simulation period
  • Average Values: Mean values over simulation period
  • Duration: Time periods for different conditions

System Health Indicators​

  • Flooding: Indicates system capacity issues
  • Runoff Ratios: Indicates imperviousness and infiltration
  • Inflow Patterns: Indicates system connectivity
  • Mass Balance: Ensures conservation of mass

Limitations​

  • Aggregated Data: Returns system-wide totals only
  • No Component Details: Individual component data is nullified
  • Limited Filtering: Basic time-based filtering only
  • No Caching: Direct database queries each time
  • Synchronous: Some operations are synchronous

Future Enhancements​

  1. Component Details: Option to include component-level data
  2. Advanced Filtering: Time range and condition filtering
  3. Caching: Implement result caching for performance
  4. Real-time Updates: Support for live system monitoring
  5. Custom Aggregations: User-defined aggregation functions